This documentation is from Prof. Helmut Dersch and the copyright belongs to him totally. Thanks him for his excellent PTViewer.

PTViewer Documentation

Updated for Version 1.8.2
January 2, 2001
Helmut Dersch
Technical University Furtwangen
der@fh-furtwangen.de

PTViewer is an open and free Panorama viewer. It is written in the Java language (v.1.0.4) and should run in any java-enabled browser. From Version 1.4, there is an additional Java-application which runs without any browser on Java 1.1 installations.

Its main features are:

Download the latest version of PTViewer from this site
 

Images

PTViewer uses equirectangular panoramic images, which must cover 360° horizontally. Vertical coverage may be any value between 0° and 180°. In the equirectangular projection, both horizontal and vertical axis are proportional to the viewing angle. Therefor, a full spherical panorama  has  an aspect ratio of exactly 2:1. An example, which is taken from the Virtual tour of Marburg from this site is shown below:

The "Pan", "Tilt" and "FOV" values which you can set to override the defaults, are easily deduced from the figure above. JPEG and GIF images are supported. Any size for the source panorama can be used, however, memory requirements for image decompression may be quite large for some java engines. Suitable images can be created using various commercial packages (LivePicture, iMove) or the free PanoTools software from this site.

Cylindrical images as used in QTVR or other viewers have to be converted to the equirectangular projection, which can easily be accomplished using the free Panorama Tools from this site.  Use the following procedure:

Open the cylindrical image in Photoshop (or any other Graphics program with the Panorama Tools plug-in installed). The example below is such a cylindrical rendering of the scene above as might have been used for QTVR. It is converted to PSPhere/equirectangular format using the remap tool with the shown settings. Notice that the image gets smaller without loosing information. The saving are quite considerable in large vertical field of view images.

Partial panoramaswith pan-range smaller than 360°and Flat Images can also be displayed. See the separate documentation for details.

Image format may be JPEG (recommended for photographs) or GIF. To protect images against theft PTViewer images may be encrypted using the PTCrypt utility. There are various encryption options available, consult the PTCrypt documentation for details. Encrypted images are recognized by their extension (jpa, jpb, jpc,..) and can not be read by standard graphics programs. Using the stronger encryption features, they can't even be read by PTViewer if they are moved or copied from their original location.
 

Controls

PTViewer is controlled by the html-file which sets the applet parameters. As a minimum, the size of the viewer window and the name of the image file have to be set. This section of the html file may then look like:
 

<APPLET archive=ptviewer.jar code=ptviewer.class width=320 height=200>
<PARAM name=file   value="pano.JPG">
</APPLET>
The java code is contained in the file ptviewer.jar, which has to be placed in the same directory as the html-file, or you may provide a different path in the archive tag.  Some viewers can not read jar files, and you have to provide the uncompressed class file instead.

PTViewer may be used with these minimum controls. The file SimplePano.html in the distribution demonstrates this minimum functionality which is sufficient to view and navigate the panoramic images.

PTViewer supports many more commands, which are all set by adding more PARAM-tags inside the APPLET tag. This is a list of options:

A list of panoramas can be defined using the pano0/1/2/3.. tag. This is required for use with the newPanoFromList() function. Using this feature PTViewer can be scripted without the need for a scriptable java-implementation. A panorama description consists of parameter tags similar to paramater tags in html pages. Each parameter tag is placed between braces. It consists of an identifier, followed by the equal sign ('=') followed by the value. The parameters have identical names as the above described tags, and are available except the view-related tags. An example pano tag: 
 <PARAM name=pano0  value=" {file=images/pano.jpg}
            {pan=-45}
            {tilt=-50}
            {fov=80}
            {fovmax=120}
            {fovmin=30}
            {auto=0.5}
            {hotspot0=x1141 y207 cff0000 n'Marburger Schloss'  u'Controls.html'}
            {hotspot1=x311  y265 c00ff00 n'Pfarrkirche'        u'Controls.html'} ">
Please note that no quotes are used to enclose the parameters to the right side of the equations. Also, no spaces should be used on the left sides, since the simple parser used to read these parameters might get confused.

Download feedback for the panoramic image is provided in two different formats depending on whether a 'wait'-image has been set. If not, then download feedback is provided by a message "Loading Image....X% complete" with X being the proper percentage. If a waitimage is specified, a progress bar is plotted inside the image. Size, location and color of this bar can be specified using the 'bar_..' tags. Download feedback indicates 80% when the image file has been loaded, and 100% after the image has been decompressed.

Hotspots

Hotspots may be used to link other documents to specific points in the panoramic image. Hotspots are set using the 'hotspot' parameter in the APPLET tag. The active region of the hotspot may be specified in 4 different ways:

  1. Default (no specifications). A square region 24x24 pixels (in the viewer!) surrounding the x/y coordinate of the hotspot.
  2. Rectangular (specify a/b). A rectangular region (in the panoramic image!) limited by point x/y to the left and a/b to the right .
  3. Arbitrary shape (specify mask image m for each hotspot) The white regions of the mask image (in the panoramic image).
  4. Arbitrary shape (specify grayscale hotspot image hsimage, one for all hotspots, same size as panorama). The gray value of a pixel (0-254)  determines the hotspot number it belongs to. 255 (white) means 'no hotspot'. This last method can not be mixed with the other three cases.
Parameters in hotspot description lines and in other multi-parameter tags (static hotspots, ROI, etc) consist of an identifier, which is a single character, and its value. Parameters are separated by spaces, or, if they contain spaces, may be quoted by single quotes (') or any other letter, which is defined as quoting charcter by preceding it with the letter $. Example
 
<PARAM name=hotspot0 value="x1141 y207 u'pano.html' n$+Marburger 'Schloss'+ ">
Each hotspot description  consists of 4 mandatory parameters: The following are optional parameters: Options may be specified in any order.

These are examples for hotspot tags: 

    <PARAM name=hotspot0    value=" x1141  y207 cff0000 n'Marburger Schloss'         u'pano.html'">
    <PARAM name=hotspot1    value="  x311  y265 c00ff00 n'Pfarrkirche'              u'http://www.fh-furtwangen.de/~dersch'" >
    <PARAM name=hotspot2    value="  x386  y506 c0000ff n'Stairs'                   u'pano.html' ">
    <PARAM name=hotspot3    value="  x209  y82  i'images/hs.gif' n'Sky'             u'pano.html' ">
    <PARAM name=hotspot4    value="  x393  y386 c00f0f0 n'Entrance'                 u'javascript:test()' ">     <PARAM name=hotspot5    value="  X50   Y50  cf0f0f0 n'Center'                   u'panos.jpg' ">     <PARAM name=hotspot6    value="  x776  y124  cf0f0f0 n'Lamp' m'images/lmask.gif' p i'images/popup.gif' u'pano.html'  ">
Hotspots may be stacked. If one hotspot has identical x and y coordinates as another hotspot prior in the list, it is assumed to be identical. The mask of the prior hotspot will then be reused. If this hotspot gets activated by clicking the mouse, or moving the mouse over it, the appropriate actions of both hotspots are executed. Arbitrary many hotspots may be stacked at any position. The file 'Controls.html' of the distribution contains this example for a stacked hotspot:
 
 <PARAM name=hotspot6 value="  x776  y124   n'Lamp' m'images/lmask.gif'  i'ptviewer:PlaySound(0)'  u'Controls.html'  ">
 <PARAM name=hotspot8 value="  x776  y124 p  i'images/popup.gif'   ">


A common use for hotspot images is the tripod cap, ie a small logo at nadir position which covers the inevitable tripod head in full spherical panos. This logo usually links to the author of a panorama. See these examples which use normal, and warped hotspot images for this purpose.
 
 
 
 

Static Hotspots

From Version 1.1. PTViewer supports static hotspots. These are static locations in the applet window which can be used like clickable image maps in html. The syntax to set these static hotspots is similar to the panorama hotspots. Note that all coordinates are absolute pixelcoordinates in the applet window. Static hotspots are set using the 'shotspotNumber' parameter in the APPLET tag. Each static hotspot description must consists of 5 mandatory parameters:

The following are optional parameters: Here's an example for static hotspots: 
 <PARAM name=shotspot0   value=" x236 y186 a250 b200 u'ptviewer:startAutoPan(0.5,0,1)' ">
 <PARAM name=shotspot1   value=" x250 y186 a264 b200 u'ptviewer:stopAutoPan()' ">
 <PARAM name=shotspot2   value=" x264 y186 a278 b200 u'ptviewer:startAutoPan(0,0,0.97)' ">
This example shows the use of the ptviewer: controls which can be used like URLs and javascript: functions. See the next chapter for details.

Static Hotspots may be stacked like normal hotspots. If one hotspot has identical x,y, a and b coordinates as another hotspot prior in the list, it is assumed to be identical. If this hotspot gets activated by clicking the mouse, or moving the mouse over it, the appropriate actions of both hotspots are executed. Arbitrary many hotspots may be stacked at any position.

Preview Panoramas, Regions of Interest, Zoomable Features

The panoramic image used in PTViewer may be dynamically assembled during viewing. This is accomplished by providing 'roi' tags. This tag consists of three parameters with a similar syntax as the other list tags:

Example 
<PARAM name=roi0  value=" i'myimage.jpg' x50 y80 ">
The image 'myimage.jpg' is inserted at coordinates 50/80 into the panoramic image. The image must fit into the panorama without extending to the right or bottom.

If the panoramic image used as source in PTViewer should have higher resolution than the image supplied in the 'file' tag, then additional parameters pwidth and pheight have to be supplied, which specify width and height. The file-image is internally scaled up to pwidth/pheight, and then the full resolution roi-images can be inserted. The following code preloads a small image (600 * 300 pixels) and later inserts a full size (1800 * 900 pixels) version. The preload is visible almost instantly:
 

<PARAM name=file  value="SmallPano.jpg">
<PARAM name=pwidth  value="1800">
<PARAM name=pheight  value="900">
<PARAM name=roi0  value=" i'LargePano.jpg' ">
Preparing the scaled image "SmallPano.jpg" may be tricky: Most Graphicsprograms slightly shift images upon scaling by some fractions of a pixel size vertically and horizontally. This shows up during progressive download as annoying movement of parts of the image. Therefore, the scaling-algorithm has to be the exact inverse of that used by PTViewer, which scales relative to the center of the image. This is also the scaling algorithm used in the 'Correct'-tool of the Panorama Tools plug-in software, which is recommended for this task.

By default, all ROI images are loaded and inserted at initialization time. This can be disabled by setting the parameter loadAllRoi to "false". It is then possible to load individual roi images using the command ptviewer:loadROI( int number) (or the corresponding javascript version). This command can be linked to any hotspot or triggered by javascript, see the chapter on scripting below.

If no "file" parameter is set, but nevertheless the panorama width ("pwidth"), then ptviewer displays a grid, with horizontal and vertical lines spaced by 10°. This grid can then be filled progressively by ROI images to create a progressive download. The background and foreground colors of this grid can be set using the parameters "grid_bgcolor" and "grid_fgcolor". They default to white and black.

Large zoom ratios (>3:1) are better implemented using the PTZoom extension.
 

Sound and Other Media

Sound files of type au, aiff, wav and midi are supported in PTViewer 1.2. They should be specified in a list using the parameters sound0, sound1, sound2, etc. Specify the name of the sound file. They can then be played back using the ptviewer command 'PlaySound(n)' with n being the number of the sound in the list. This command can be linked to any normal and static hotspot, or linked to the popup function, or called from javascript. Please note that current browsers usually implement Java 1.1, which only supports '.au' file. Using '.gsm' files is possible with a small extension.

Many more media formats are available if JMF is installed on the host computer. These include avi-video, linear quicktime video, flash 2,  mpeg1/2/3, many soundformats etc. From version 1.7.2 of PTViewer, JMF media are loaded via the optional PTMedia extension.

Configurable Controls

From Version 1.1 PTViewer can be configured to control almost any internal function from within the applet. No html-browser is required and complete VR tours can be displayed using just the appletviewer. The basis for this is an internal scripting system which works like a subset of javascript. Many PTViewer-functions can be called like URLs using the prefix "ptviewer:". They can be used as u-tag in both static and normal hotspots, see the examples for static hotspots above. This is a list of accessible functions which is similar to the corresponding list of javascript functions:
 

Some functions require arguments, eg. startAutoPan(). These arguments should be supplied as constants. Allowed is  startAutoPan(2,3,1.2), not allowed is startAutoPan(1+0.5, tilt, zoom*1.05).

Scripting

PTViewer can be scripted by the html document. Several functions are available to control navigation, zooming, panning and jumping to specific locations. The syntax follows the usual javascript rules. All ptviewer commands from the list above are available as javascript commands also. In addition, the following commands are available only in javascript:

See the html file ditributed with the java viewer for an example. It uses an image map created by Andrei Bodrov  and links some of the controls to specific buttons. You may also link to standard javascript buttons in your document as used for the 'gotoHS' links.

For a more descriptive list of all publicly accessible parameters and functions in ptviewer, see the API-documentation generated using javadoc.

Loading New Panoramas from Running Applets

New Panoramas can be loaded using the newPano() and newPanoFromList() functions. The newPanoFromList() function requires the previous definition of a list of panoramas, whereas the newPano() function supplies all definitions in a string argument.

Both functions  can be used from internal controls using the URL-tag 'ptviewer:newPanoFromList(num)', in hotspots (normal and static hotspots) or using javascript from the browser. All parameters are reset with the exception of the view-parameters (width/height/offset), the wait image, the frame image, all static hotspots and  sounds.Static hotspots, frame, wait image and  sounds may be newly set in the panorama description, in which case the old values are discarded. See the example Controls.html of the distribution.
 
 

Calling Javascript functions from PTViewer

PTViewer can call user supplied javascript functions. To be able to call javascript from the applet, the parameter mayscript must be set. This can be done in the applet tag:
 

<APPLET  name="ptviewer" archive=ptviewer.jar  code=ptviewer.class width=320 height=200 mayscript=true>
There are three possible ways to call javascript from PTViewer:  My own tests have shown that interaction of javascript with java may be quite unstable and does not work on all browsers, eg not on the combinations Mac/IE. It is recommended to check for a safe combination by query of the javascript navigator object, and provide an alternative for unsafe systems.
 

Large Images

Some browsers have limits on the maximum size of linear arrays, eg 4MByte on Netscape, even if more system memory is available. This limits the maximum size of images some java viewers can handle, eg LivePicture's IVR-viewer can't read spherical images of more than 1500 pixels width. PTViewer can read much larger images by internally splitting the image into chunks of smaller pieces. The size of these chunks can be set via 'maxarray' parameter tag. The default value is #80000 hexadecimal, which corresponds to roughly 500000pixels, ie 2Mbyte (4byte = 1pixel). Unfortunately, this splitting causes other Browsers (Internet Explorer) to download images slower than normal. For best performance one can set the maxarray parameter depending on the browser, see the javascript code in the example above. However, in most cases this is not needed and the default value works for any browser.
 

Packaging files using the Jar utility

All files belonging to a VR-scene (images, sounds, textfiles) can be packaged into one single archive using the Jar archiving tools. This is a convenient way to store, mail and present  virtual tours. Only the html-file has to be kept separate. Double-clicking this html-file launches the browser, which then automatically extracts and displays the content of the file. See the separate documentation about packaging tours for details.
 

Authoring

From version 0.8, PTViewer has some additional helper commands to aid authoring of documents:

PTViewer Java Application

This application uses the Java-applet 'PTViewer' and a custom AppletStub to implement a standalone cross platform spherical panorama viewer. Using the internal scripting capability of PTViewer, full featured VR-tours can be displayed. The same html-file used for display in a browser can be reused for the application.Using the Java archiving tool 'Jar', it is possible to pack tours into one self-displaying file. See the separate documentation describing this feature.
 

Using the Application:

After double-clicking the application, a file dialog is presented. Choose any panoramic image in jpeg format, eg the file pano.jpg in the distribution. Images are recognized by the extension jpg or jpeg. Alternatively, you may specify a html-file, eg the file example.html. PTViewer extracts the <applet>-tag and all parameters relevant for display, and shows exactly the same tour as can be seen in a browser, with the following restrictions:

The application allows the user to resize the viewer window. If the viewer-size has not been set (parameter view_width and view_height), the applet will also be resized according to the window. If the viewer-size has been set (most likely to fit the applet into a frame) then the applet does not react to window size changes. Do not resize the window while the applet loads the image.

PTViewer does not display a file dialog if a html-file with name 'default.html' is present in the applications directory. PTViewer then loads and processes this file. This can be used for self-displaying tours. PTViewer may also be called by other java applications. The main() method of the ptvjapp class should be called with the filename of an image or html-file  as argument.
 

Extensions: PTObject, PTMovies, PTCompass, PTMedia, PTZoom

Using the API-documentation, it is possible to extend PTViewers capabilities using additional applets. Five such applets are included in the distribution: PTObject, PTMovies, PTCompass, PTMedia and PTZoom. See this documentation about the use of these applets, and how to build your own extensions.

More Resources and Examples:

License

PTViewer is distributed under GNU license, see the file 'Copying' in the distribution. Sources are not available yet, but will be published  with  a later version. You may distribute the PTViewer applet freely, but you have to make sure that recipients have this same right, see the license for details. Practically, this means that you have to provide at least a link to the download page of PTViewer.
 
 

Copyright ©2000,2001 Helmut Dersch
der@fh-furtwangen.de